Code reviews: a necessary evil or a developer’s best friend? We believe the latter. The code review process—where one or more developers review code authored by another developer to ensure it’s codebase ready—is a cornerstone of software development. Code reviews help bolster code quality, encourage knowledge sharing, and accelerate professional growth.

But let's face it, both giving and receiving code reviews can be a bit of a pain. That's why we’ve tapped into the expertise of GitHub engineers to bring you actionable insights and tips to ease the process. Whether you’re a seasoned pro or just dipping your toes into the world of code review, this edition of The GitHub Insider offers some sage advice to elevate your code review game.

We also have to give a huge shout out to our very own Sarah Vessels, who authored an amazing blog post on her philosophy of code reviews and inspired this newsletter. ✨

Now, let’s jump in.

🔖 A quick history of code review

Code reviews have come a long way since their humble beginnings. Once a manual, often tedious process involving printed code, code reviews have evolved significantly with advancements in technology. The advent of version control systems, like Git, in the late 2000s totally revolutionized the process and transformed it into a streamlined, collaborative activity. And today, platforms like GitHub have made asynchronous code reviews the norm!

⏳ Did you know, the idea of code reviews dates back to the 1970s? One of the key figures in this development was Michael Fagan at IBM, who in 1976 introduced the concept of Fagan Inspection, a structured process for reviewing documents, including code, in a formal and systematic way. ⌛

History lesson aside, let’s get into those tips…

#1: Clarity, clarity, clarity

When providing code reviews (most often done in the pull request), make sure you’re clear about the feedback you’re providing. You can follow these best practices:

• Make sure your team understands which of your comments are your own personal preference and which are essential for approval.
• Provide an example of the approach you’re suggesting, so your team has a good understanding of what you’re trying to communicate—even better if it’s an example from the same repository as the pull request.
• Be clear about exactly when your suggestions should be implemented. If you’re suggesting that existing, unchanged code should be refactored, or an additional case should be handled, make sure to specify whether those suggestions are precursors to approval. If the pull request is fine without your suggestions, note that.

For example, here is a review comment that is specific and communicates suggested edits well:

This comment provides specific details, references specific issues, suggests a resolution, and provides an explanation.

Conversely, take a look at this review comment:

Obviously, this comment isn’t very helpful as it doesn’t state what the reviewer doesn’t like or offer an alternative for how it could be done.

Consider these alternatives:

#2: Standardize code reviews with automation

Consistency is key when it comes to code reviews. 🔑

Try to leverage repo-level automation tools like CODEOWNERS files and branch protection rules to establish clear guidelines across your teams. You can also consider using project boards, like GitHub Projects, for tracking pull requests, especially in teams managing shared components.

You can use GitHub Projects to track issues and pull requests.

And remember, communication is essential. For teams that are heavily relied on, you can consider using bots to provide automatic updates on review timelines. Ultimately, by standardizing your code review process, you'll improve efficiency, enhance code quality, and foster a smoother development workflow.

❗ While automation can handle many aspects of the process, human interaction still remains vital. You’ll need to document your team's review process, including expectations, turnaround times, and automation details.

#3: Ask questions, challenge assumptions

Code reviews are a two-way street. As a reviewer, your questions can uncover potential issues, deepen your understanding of the codebase, and help share important knowledge. Remember, the author is the domain expert, so trust their judgment and use questions to clarify your understanding. And as an author, welcome questions as an opportunity to explain your reasoning and share insights. Be open to feedback and consider using automated tests to bolster your claims.

It's crucial to approach code reviews with an open mind, regardless of the reviewer's experience or the code's location. Everyone makes mistakes, and your fresh perspective can be invaluable. So, don't hesitate to ask questions, even if they seem basic. Your curiosity can benefit the entire team. By embracing a culture of inquiry and challenging assumptions, you can significantly improve the quality of your code and the overall development process. ✨

Want to take your code review discussions to the next level? Check out GitHub Discussions! This nifty feature offers a space for broader conversations around code, best practices, and project-related topics. It's a great way to share knowledge, collaborate, and build a stronger team dynamic outside of the pull request workflow.

Well, that’s a wrap on this edition of The GitHub Insider! Remember, code reviews are like fine wine: they improve with age (and feedback). And until next time, keep refining your skills, and don't be afraid to merge your knowledge with others!

Get started with GitHub Discussions

---

✨ This newsletter was written by Sara Verdi and produced by Gwen Davis. ✨

---

The world’s leading AI-powered developer platform.